Git

Git is a distributed version control system

• each client (user) has its own local copy
  => local repository

• which can be synchronized with a copy stored on external server
  => remote repository

Git workflow

Source: http://bit-booster.com/graph.html

GitHub

GitHub is a commercial Git repository hosting service
with some extra functionalities:

• cloud-based service

• web-based graphical interface

• issue tracker

• basic project management functionalities, access granting etc.

• Extended free plan:

  • unlimited private repositories
  • unlimited collaborators

GitHub repo page

Why do you (might) need it?

Why do you need it for yourself?

Source: https://smutch.github.io/VersionControlTutorial/

Why do you need it for yourself?

• track changes: always have the most recent version of a file, while keeping the entire history of changes
  

• experiment: you can experiment with your code
  and revert changes if needed
  

• multiple instances: you can have several version of your code
  and easily switch between them
  

• in case of using a remote repository (e.g. GitHub):

  • backup in a cloud (with all the above)
    
  • easy access from multiple devices
    
  • use issues to make notes to the future self

Why do you need it for sharing?

• searchable repositories
  
• created to share a code
  
• easy to attach a web-based description of your code (README.md) file
  e.g. https://github.com/r-spatial/leafgl
• easy to install directly from github
  (e.g. remotes::install_github("r-lib/remotes") )

Why do you need it for collaboration?

• Git is distributed: all collaborators work on their own local copy
  (code, its versions and all the history of changes)
  
• All collaborators can work simultaneously
  
• Grant access even to private repositories
  
• Share (and test!) a developer version of your code
  
• pull request: revise changes before merging them
  
• contributions are transparent
  
• issues:
  • search for help, ask questions and discuss, request new features / modifications
    
  • easy to link to commits, cross-connect to other issues, bug tracker
    
  • assignees, mentions and notifications

Repo

Create a remote repository on GitHub

Go to your GitHub account and select New repository

Create a new repository on GitHub

Name your repository

• Should be a character string (without space)

• No official naming convention, but hyphens are mostly used to separate words

• Great repository names are short and memorable.

Besides repository name you can:

• add a brief description (read: you should)

• create README.md file (yes, you want to do that)

Public or private?
Be brave and make a decision

• public repository is, well, public (anyone can see it, clone it etc.)

• private repository is visible only for you or anyone you grant an access to it. It is a good solution for:

  • testing, experiments, etc.
  • early-stage projects (for some reason you don’t want to share it, yet)
    
  • all in-progress stuff
    
  • any project should not be publicly visible

Public to private or private to public?
Not a problem! (usually)

• you can change it anytime:

Add .gitignore

.gitignore contains a list of all the files that should not be included in the repo.

It’s highly recommended to inlcude .gitignore into your repository.

GitHub offers a list of .gitignore templates.
Select the one which fits you best.

Select a licence

New repo on github: summary

A brand new repository

Clone a repo

Clone creates a local copy of a remote repository

It contains all project’s files and full project’s history.

Clone a new repo

1. You need to download (clone) repo from github

Clone a new repo (RStudio)

2. Create new RStudio project…

3. …using Version Control

Clone a new repo (RStudio)

4. Paste link to the repo and select its location

Clone a new repo (RStudio)

Done!

What does (.gitignore) do?

Use .gitignore for all those files that should not be taken into account by Git so they are:

• excluded from the version control and not tracked by Git

• not inlcuded to any commit

• not pushed to remote repository

• not shared with colaborators / published

They only reside on your local machine.

What to add to .gitignore?

Anything we don’t want or don’t need to keep track of

• user-specific files / settings (e.g. MyProjectName.Rproj)
  

• notes & drafts

• data, in particular large files

• outputs of our code: tables, figures, html rendered from Rmarkdown files, etc.

• Any personal / confidential data:

  • passwords
    
  • API keys

How to understand .gitignore?

• Anything after # is ignored

• *.Rmd ingores all .Rmd files (* replace any character(s)

• !main.Rmd states that main.Rmd should be tracked (not ingored)

• test.R ignores test.R file

• /test.R ignores test.R file in a folder where .gitignore is located

• test/test.R ignores test.R file in a test folder

• test/ ignores all files in a test folder

Tip: use templates, add manually what you need.

Commit

Commit is a snapshot of the repository.

Commits are cheap.
Commit often.

Commits

Each commit has its own identifier.

You can:
+ have an access to the repository at a given stage
+ revise changes made by a particular commit

Revision of changes

Revision of chages

You can even compare binary files!
Use Display the rich diff

Commit messages

Each commit must contain a message.
Add useful, self-explanatory messages.

Source: https://imgs.xkcd.com/comics/git_commit.png

Push and pull changes

It’s all about syncing your local and remote repositories.

Git pane in RStudio

1. Pull - updates local repo using remote one
2. Push - sends changes from your local repo to the remote one
3. Options
   • Revert changes - discards changes made since the last commit
   • Ignore - adds a file (or files) to .gitignore
   • Open Shell
4. Commit selected files
5. Revise changes offered by the laste commit
6. Revise history of a project (all commits)

File states

1. Committed: form part of the repo in the current form.
   Git keeps their most recent state and full history of changes.

2. Untracked: git sees them but has no clue what’s your point, yet.

3. Staged: their current form is frozen and can be added to commit.
   In case of further changes, you need unstage and stage it again.

4. Ignored: git doesn’t see nor it’s interested whether they are changed or not.
   You need to explicitly inform git to ignore a file.

File states in RStudio

• Added: new file added to repository.

• Untracked file.

• Deleted file: it is not available in repository anymore
  important: the file can be found when browsing commits / history of repository.

• Modified: file has been changed since the last commit

Stage file in RStudy Git pane

Commit in RStudio Git pane

Add a commit message

Aborting commit due to empty commit message.

Push commit to remote repository

Once you finalize your commit, you can push your commit(s) to the remote repository.

After a while, commit becomes alive in your github repository
(you need to refresh your browser).

Changes in staged file

Workflow: remote & local

Workflow: remote & two different locals

Now it is your turn!
Make your first commit

• Stage file example_code.R file
  
• Select Commit button

Now it is your turn!
Make your first commit

• Add commit message
  
• Commit and push changes to the remote repository
  
• inspect repository on your github account

Now it is your turn!
Commit modified file

Conflicts

Source: https://imgs.xkcd.com/comics/git.png

Resolving conflicts

Conflict appears when different changes have been made to the same file since the last commit.

Conflicts have to be resolved.

Now it is your turn!
Create and resolve a conflict

Open README file directly from your github remote repository:

Edit the file, and commit changes:

Now it is your turn!
Create and resolve a conflict

Now it is your turn!
Create and resolve a conflict

Now it is your turn!
Create and resolve a conflict

Resolved!

Branch

Branch is a parallel version of a repository.

Source: https://docs.github.com/assets/images/help/branches/pr-retargeting-diagram1.png

Why to use branches?

New branch via GitHub.com

You can create a new branch via GitHub.com web:

Name convention for branches is similar to the repo one (e.g. this-is-my-new-branch)

New branch from GitHub.com to RStudio

Once you’ve created a new branch, it appears in your local repo,
just pull the remote one.

Now, you can check out to this new branch.
Any further commit will be added to this new branch, while master will be untouched.

New branch from RStudio

You can create a new branch directly from RStudio:

Now it is your turn!
Create a new branch and add a new commit

Merge

Once you are ready to incorporate the changes, you can merge them into your master branch.

It means, that all commits from a given branch will be inlcuded into your master branch.

Compare branches

Compare branches via GitHub.com

Pull request

Add a comment to the pull request

Submit the pull request

Delete unnecessary branch

Once you confirm merge, you can delete an old branch.

Go back to RStudio. Check out to master and click pull

>>> C:/Program Files/Git/bin/git.exe pull
From https://github.com/stmarcin/test_workshop
   2387ab3..4e6e32c  master                  -> origin/master
Updating 2387ab3..4e6e32c
Fast-forward
 README.md      | 1 +
 example_code.R | 5 +++--
 2 files changed, 4 insertions(+), 2 deletions(-)

Delete branch in RStudio

The branch is deleted from the remote repository, but it is still visible in RStudio pop-up menu:

Delete branch in RStudio

git fetch -p

git branch -d name-of-your-branch

Fork

Workflow with forked repository

1. Once you fork a repository you need to clone it to the local repo.

2. Once it is cloned you have to set a link to the original one.
   

3. Open Shell and write the following:

   git remote add upstream https://github.com/stmarcin/repo-for-workshop-tgis

4. Create a new branch and check-out to it.

5. Add/edit files, stage them and commit changes.
   

6. Push changes to your remote repository.
   

7. Create a Pull request

GitHub issues

GitHub issues serve to communicate with users (including yourself).

• Each issue has its own id which can be then refered to and contains its own discussion thread.
• You can refer to the issue id (#) in your commit messages, e.g. Solve #3
• You can @mention another user so they are informed about the issue.

Set up GitHub Desktop

Create a new repository

Go to File -> New repository (or Ctrl + N)

Create a remote repository

For the sake of your mental health:
use the same name for both, local and remote repository!

Add a file to your local repository

You can just simply copy a file to your repo’s folder:

GitHub desktop offers default commit messages
(such sophisticated as: Create file.txt or Update file.txt)

Commit and push changes

Once you commit you’ll see, that your changes are not pushed to your remote repo (1).

You need to push commits manually (2)

Create a new branch

In order to create a new branch go to:
Branch -> New Branch (or Ctrl + Shift + N):

Once you have created a new branch, confirm which branch you are currently on:

Update a branch

I have accidentally commit to master branch instead of the my-first-new-branch.

GitHub Desktop allows you to Update your new branch from master.

Create a new issue from GitHub Desktop

Go to Repository -> Create issue on GitHub (or Ctrl + i)

You can directly refer to the issue writing a commit message:

Ignore file(s), dicard (recent) changes

Select a file in Changes pane so you can:

• add a file to .gitignore
  
• edit a file (open in… e.g. Notepad++)
  
• discard recent changes:

Merge branch from GitHub Desktop

You need to check out to the branch you want to merge (e.g. master)

When it’s done, you can delete a branch:

Create a repo for an existing project

Do you already have R project and need to create GitHub repo for it?
No problem!

The easiest way to do it (no configuration needed):

1. Create a new repo on GitHub (remember to include .gitignore);
   
2. Clone the repo to you desktop
3. Copy your project to the one you created while cloning your repo.
4. Commit the files of your choice (adding unnecessary to .gitignore)

Done!

Using {usethis} package

install.packages("usethis")

usethis::use_git()

usethis::use_github()

On GitHub while creating repository

On GitHub whenever

In RStudio from Git pane

You can select which files you want to add to .gitignore

In the next step you can select where .gitignore will be located
and add whichever files you want, even those which do not yet exist

In R using {usethis} package

usethis::use_git_ignore(ignores, directory = "."

usethis::edit_git_ignore()